This file : manipCols Help 
        Created : 2000-05-27  08:28:25 
        Last modification : 2001-03-13 09:40:17
Author : Bernard Desgraupes 
e-mail : <berdesg@easynet.fr> 
Web-page : <http://perso.easynet.fr/~berdesg/> 

Comments :  help file for the columns manipulation package in Alpha.
This file should be located in the Help subfolder of Alpha's folder
to show up automatically in the Help menu when Alpha is loaded.  

(c) Copyright : Bernard Desgraupes 2000, 2001
        All rights reserved.


Contents:
______________
 Introduction
 Basics
 Installation
 Menu Items
 Key Bindings
 Preferences
 Version History
 More Cols Package
 Known problems
 License terms
______________


====================
Introduction
====================

The 'manipCols' package is a feature which    allows    to    do    various
manipulations with the columns of any tabulated material i-e  a  series  of
lines in which items are separated by a tabulation or by any other specific
character (like & or a tabulation or a colon, a comma, an  endash  etc.  or
even the space character). Once it is installed and activated,  it  adds  a
submenu called <Columns> to the <Text> menu in Alpha.  The  items  of  this
submenu are explained below. Basic manipulations  are  copying,  inserting,
appending, twiddling,  deleting,  sorting,  numbering  and  (un/)equalizing
columns, formating text in columns.


============
Basics
============

-Columns selection-
to select one or several columns, put the cursor anywhere in  the  text  of
the top left item (or "cell") you want to select, press  the  mouse  button
and,  without releasing the button, go to the text of the bottom right item
you want to select.
This will hilite a region which is much more than what  you  want  but  the
package will consider only the columns located between the top  and  bottom
positions.
Here is an example (from Romeo and Juliet). We suppose here that each  word
is separated by a tabulation (any single  character  can  be  chosen  as  a
separator, even the space character; see below) :
Gallop	apace,	you	fiery-footed	steeds,
Towards	Phoebus'	lodging;	such	a	waggoner
As	Phaethon	would	whip	you	to	the	west,
And	bring	in	cloudy	night	immediately.

Put the cursor in the word 'you' (first row, third word), press  the  mouse
button and, without releasing it, go to the word 'whip' in the  third  row,
then release : you have selected the following region
you	fiery-footed
lodging;	such
would	whip

even though all the words from 'you' to 'whip' are hilited.  We  have  thus
selected columns 3-4 and rows 1-3.
It is sometimes difficult to be sure what has been selected because columns
are not aligned vertically so  you  can  check  this  using  the  <Colorize
Columns> menu item : only the selected columns will be colorized like so
Gallop	apace,	you	fiery-footed	steeds,
Towards	Phoebus'	lodging;	such	a	waggoner
As	Phaethon	would	whip	you	to	the	west,
And	bring	in	cloudy	night	immediately.

So dragging the mouse from position (a,b) in a table to position (c,d) 
selects columns 'a' to 'c' and rows 'b' to 'd'.

If you want to have a better vertical alignment of your columns you can use
the <Equalize Columns> menu item. Select the region  as  above  and  select
<Equalize Columns> in the <Columns> menu. The result will be :
Gallop 	apace,  	you     	fiery-footed	steeds,
Towards	Phoebus'	lodging;	such        	a      	waggoner    
As     	Phaethon	would   	whip        	you    	to          	the	west,
And    	bring   	in      	cloudy      	night  	immediately.

By the way, equalizing makes it very easy to  use  rectangular  hiliting  :
select a region with the mouse holding the option key down.


-Columns separator-
It must NECESSARILY be a SINGLE character. 
Default is the tabulation character <\t>. 
With Latex you might want to choose '&' as a separator for \array or \table
environments:
    \begin{tabular}{|c|c|c|}
	\hline
    you & fiery-footed \\
    lodging; & such \\
    would & whip \\
	\hline
    \end{tabular}
You can even use the  'space'  character  as  a  separator.  See  also  the
<Columns to Latex> item below.

-Caveat-
* the cursor can be positioned anywhere in a "cell"  :  the  entire  column
will always be selected.

* you do not have necessarily to colorize the selected region. This is just
handy for visualisation. BEWARE  that  this  procedure  removes  all  other
colors in your document (this proc might be improved later).

* columns are numbered from 1 to n (see the messages in the status bar).

* hiliting must still be there if you want to  apply  a  manipulation  like
copying, inserting, appending, twiddling, deleting columns.

* note that (since version 0.5b) you DO NOT have anymore to escape (i-e put
a backslash before) the special characters like 'backslash' \ or 'dollar' $
or 'circumflex' ^ or 'endash'  -  etc.  The  package  takes  care  of  this
internally. The tabulation character though is represented by '\t'.

* all the actions are undoable (with cmd-Z).


-Text columnizing-
There are tools to format text in vertical justified  columns  (single
or multiple).  This  will  be  very  handy  to  prepare  nice  looking
documentations, help files, etc. All the  paragraphs  in  the  present
file have been justified with this tool. Everything is parametrizable:
number of columns, left margin, text width.
Here an example of multicolumnizing :
Gallop  apace,        you	to the west, and bring in	That runaways'  eyes  may
fiery-footed      steeds,	cloudy night immediately.	wink, and Romeo  leap  to
towards Phoebus' lodging;	Spread thy close curtain,	these arms,  untalk'd-of,
such  a    waggoner    as	love performing    night!	and unseen !
Phaethon would  whip  you


-More examples-
You can now select a region and experiment : here are some examples applied
to the previous selection.

'Deleting'
Gallop 	apace,  	steeds, 
Towards	Phoebus'	a       	waggoner    
As     	Phaethon	you     	to          	the    	west,       
And    	bring   	in      	cloudy      	night  	immediately.

'Copying, selecting the first two lines and appending'
Gallop 	apace,  	you     	fiery-footed	steeds,	you         	fiery-footed
Towards	Phoebus'	lodging;	such        	a      	waggoner    	lodging;    	such        
As     	Phaethon	would   	whip        	you    	to          	the         	west,       
And    	bring   	in      	cloudy      	night  	immediately.

'Copying, selecting the second column and inserting'
Gallop 	you     	fiery-footed	apace,  	you     	fiery-footed	steeds,
Towards	lodging;	such        	Phoebus'	lodging;	such        	a      	waggoner    
As     	would   	whip        	Phaethon	would   	whip        	you    	to          	the	west,
And    	bring   	in      	cloudy      	night  	immediately.

'Twiddling'
Gallop 	apace,  	fiery-footed	you     	steeds,
Towards	Phoebus'	such        	lodging;	a      	waggoner    
As     	Phaethon	whip        	would   	you    	to          	the	west,
And    	bring   	in      	cloudy      	night  	immediately.

'Sorting Columns'
Gallop 	apace,  	lodging;	such        	steeds,
Towards	Phoebus'	would   	whip        	a      	waggoner    
As     	Phaethon	you     	fiery-footed	you    	to          	the	west,
And    	bring   	in      	cloudy      	night  	immediately.

'Selecting the first two lines and reverse sorting rows'
you         	steeds, 	apace,      	Gallop      	fiery-footed
waggoner    	Towards 	such        	Phoebus'    	lodging;    	a           
As          	Phaethon	would       	whip        	you         	to          	the	west,
And         	bring   	in          	cloudy      	night       	immediately.

'Selecting all four lines and inserting rows numbers'
1	Gallop 	apace,  	you     	fiery-footed	steeds,
2	Towards	Phoebus'	lodging;	such        	a      	waggoner    
3	As     	Phaethon	would   	whip        	you    	to          	the	west,
4	And    	bring   	in      	cloudy      	night  	immediately.

etc. etc.


====================
Installation
====================

-Automatic installation-
Open the "OPEN TO INSTALL" file. Opening this file indicates to Alpha  that
a new package has to be installed  :  the  procedure  is  automatic.  Alpha
knows where to store the different elements of your manipCols package.

-Manual installation-
1- put the "manipCols.tcl" file in the "Packages" subfolder  of  the  "Tcl"
folder which is located at the same level as your Alpha application
2- put the "ManipCols Help" file in the "Help" folder located at  the  same
level  as your Alpha application. Next time you launch Alpha, you will have
a "ManipCols Help" item in the Help menu.
3- launch Alpha. You have to  rebuild  the  package  indices  and  the  Tcl
indices. <Rebuild Package Indices> is in  the  Config->Packages  menu,  and
<Rebuild Tcl Indices> is in the Tcl menu.
5-  quit Alpha and relaunch it : that's all there is to it.

-Activating the manipCols feature-
Go to "Config-->Preferences-->Menus and Features" and select  'Manip  Cols'
in the features list by checking the corresponding checkbox.

-After installing- 
Have a look at the Manip Cols preferences in the <Packages> submenu of  the
<Config> menu. More explanations below.


====================
Menu Items
====================

Almost all of these items suppose you have selected columns : see above 
how to select columns.

<Copy Columns>		Copy the selected columns in the MacOS system
			scrap.  Note  that  if  no  region  has  been
			selected or hilited,    the    entire    line
			containing the cursor will be copied.
<Insert Columns>	Insert columns from the system  scrap  BEFORE
			the first selected column.
<Append Columns>	Append columns contained in the system  scrap
			to the  right  of  the  selected  lines.  The
			procedure will append as much as it can :  if
			you have selected a  region  with  less  rows
			than the material  contained  in  the  system
			scrap, it will ignore the remaining lines.
<Twiddle Columns>	Exchange the leftmost and right most  columns
			of your selection. Note that  there  must  be
			enough elements on each    row    to    allow
			twiddling : if not the  procedure  will  fail
			and send  an  alert.  This  can  easily  been
			solved by using the <Complete Rows> item.
<Colorize Columns>	Colorize the selected items. This  is  useful
			to visualize a selected  region  and  control
			that it contains what you want.  Please  note
			that you will lose any colorization  you  did
			previously in your file. This point should be
			improved later. So use with care.
<Cut Columns>		Delete the selected columns and send  a  copy
                        to the system  scrap  so  that  they  may  be
                        pasted, inserted, appended elsewhere.
                        All the columns to the right of the selection
                        will be shifted left.
<Delete Columns>	Delete the selected columns.
<Equalize Columns>	This proc calculates the  maximum  length  of
                        each of the selected columns and appends  the
                        necessary amount of blank space so that  each
                        column has a  unique  width.  This  allows  a
                        perfect vertical alignment to make selections
                        easier. Equalizing columns makes it very easy
                        to use rectangular hiliting : select a region
                        with the mouse holding the option key down.
    When pressing the <option> key down, the previous item becomes :
<Unequalize Columns>	This is the opposite of the previous items  :
			any blank space at the right of a "cell" will
			be trimed.
<Right Justify>		To right justify the selected columns.
    When pressing the <control> key down, the previous item becomes :
<Left Justify>
    When pressing the <option> key down, the previous item becomes :
<Center>
          This is easy to remember : the control, option  and  command
          keys are in this order on the left of the  keyboard.  So  to
          left justify, press the leftmost key  (<control>  key)  when
          opening the menu etc.

<Complete Rows>		In case all the rows do  not  have  the  same
			"length" (i-e number    of    items),    this
			procedure will add empty   cells    to    the
			incomplete rows.
<Columnize Text>	To justify the selected text  :  it  is  left
                        and right  justified    vertically    in    a
                        rectangle. The values for the left margin and
                        for the total text width can be set with  the
                        <Set Margins> item. Default  values  in  Text
                        mode are 5 and 75.
<Multi Columnize Text>	To put text in multiple  columns  like  in  a
                        newspaper. You are prompted in the status bar
                        to choose  the  number  of  columns  (default
                        value is 2).
    When pressing the <option> key down, the previous item becomes :
<Uncolumnize Text>	To  undo  the  previous  command  :  all  the
                        columns of a table will be put one  over  the
                        other in a single column.
<Insert Rows Numbers>	Insert the number of the row at the beginning
			of the selected lines. Numbers are  separated
			by the current  separator  and  constitute  a
			separate column.
    When pressing the <option> key down, the previous item becomes :
<Insert Numbers From...> The same as the previous except that you are
			prompted to choose the starting  number.  The
			last number reached in a  previous  numbering
			is proposed as a default choice.
<Sort Columns> or
<Reverse Sort Columns>     with the <option> key
<Num Sort Columns> or 
<Reverse Num Sort Columns> with the <option> key
			This allows different  kinds  of  sorting  of
			columns in the selected region.  Sorting  can
			be done in increasing or decreasing order, in
			litteral (1 before 11 before 2) or  numerical
			order (1 before 2 before 11). Sorting is case
			insensitive. If several columns are  included
			in the selected region,  sorting  applies  to
			the left one.
<Sort Rows> or
<Reverse Sort Rows>     with the <option> key
<Num Sort Rows>
<Reverse Num Sort Rows> with the <option> key
			This allows different  kinds  of  sorting  of
			each  entire  row  in  the  selected  region.
			Sorting can be done    in    increasing    or
			decreasing order, in litteral  (1  before  11
			before 2) or  numerical  order  (1  before  2
			before 11). Sorting is case insensitive.
<Columns Separator>	Change here the character    considered    as
			columns separator.  Remember  that  you  must
			choose a SINGLE character :if not, some procs
			might not work properly. It can be of  course
			the tabulation character represented  by  \t.
			This menu item allows to do temporary changes
			(as long as you do not quit Alpha). To change
			the Columns Separator permanently go  to  the
			manipCols Preferences.
<Columns Bindings>	Brings a window with  information  about  the
			key bindings  available  when  the  manipCols
			package is active. See below.
<Set Margins>		You will be prompted in  the  status  bar  to
                        set the values for the left  margin  and  the
                        total text width.


====================
Key Bindings
====================

All the key bindings will use 'ctrl-c' (c for columns !). 
Hit 'ctrl-c', release, then hit one of the following letters :
<ctrl-c a>    to <a>ppend columns
<ctrl-c b>    to show info about <b>indings
<ctrl-c c>    to <c>opy columns
<ctrl-c d>    to <d>elete columns
<ctrl-c e>    to <e>qualize columns (left justified)
<ctrl-c f>    to insert rows numbers <f>rom a certain value
<ctrl-c i>    to <i>nsert columns
<ctrl-c j>    to <j>ustify text (not columns)
<ctrl-c k>    to <k>olorize <k>olumns
<ctrl-c m>    to center columns (m for <m>iddle)
<ctrl-c n>    to <i>nsert rows numbers
<ctrl-c o>    to sort each row in increasing <o>rder
<ctrl-c p>    to com<p>lete rows
<ctrl-c r>    to <r>ight justify columns
<ctrl-c s>    to change the columns <s>eparator
<ctrl-c t>    to <t>widdle columns
<ctrl-c u>    to <u>nequalize columns
<ctrl-c v>    to set the margin <v>alues for columnizing
<ctrl-c x>    to cut columns (e<x>tract them and copy in system scrap)
<ctrl-c z>    to uncolumni<z>e
If you use the 'More Cols' package (see  below),  you  four  more  key
bindings :
<ctrl-c h>    to convert a table to <h>tml code
<ctrl-c l>    to convert a table to a <l>atex tabular environment
<ctrl-c w>    to convert a <w>orld <w>ide <w>eb Html table to text
<ctrl-c y>    to convert an arra<y> or tabular LaTeX environment to text


====================
Preferences
====================

The <Manip Cols Prefs> item in the <Packages> submenu of the <Config>
menu allows you to make a few choices :
- the <Columns Color> variable allows you to choose the color in which
to colorize the selected columns.
- the <Columns Separator> variable allows you to  choose  the  default
character used to separate columns : this is the separator which  will
be used each time you launch Alpha and as long as you do not  override
this choice with the <Columns Separator> menu item.
- the <Min Columns Width> variable allows you to set the minimum width
allowed for columns when using the <Text Columnizing> tool.


====================
Version History
====================

0.1b	05/27/00	
                        First writing of this package.
0.2b	05/29/00	
                        Changed 'ctrl-k' to 'ctrl-c' for  keybindings.
                        Rearranged the menu items.
0.3b	05/31/00	
                        Added a <Cut Columns> item.  Added  tools  for
                        text columnizing. Added new key bindings.
0.4b	06/02/00	
                        Corrected  a  bug  in  backward  search.  Made
                        changes for Alphatk compatibility.
0.5b	06/03/00	
                        Made the  problem  of  special  characters  to
                        escape invisible for the user  :  it  is  done
                        internally. 
0.6b	06/03/00	
                        Changed the  routine  to  split  a  region  in
                        paragraphs. 
0.7b	07/01/00	
                        Added items to convert a table  to  HTML  code
                        or to a LaTeX tabular environment. Items to do
                        the reverse. Html nested tables are handled.
0.8b	08/17/00	
                        The conversion of  tables  to  Html  or  Latex
                        formats are now an independant feature  coming
                        as a complement to manipCols.
0.9b	09/20/00	
                        Added a "Colums Tutorial" item to link to  the
                        Example file.
1.0		10/06/00	
                        Added procs to  justify  some  columns  (left,
                        right, center). The columns  equalization  now
                        work on the selected columns and  not  on  the
                        entire table.
1.0.1	07/10/00	
                        Change a proc name (help::openExample  instead
                        of file::hyperExampleOpen)
1.0.2	16/02/01
                        Corrected a  bug  (misplaced  switch  item  in
                        three procs) which had no effect  in  Alpha  7
                        but crashes Alpha 8.
1.1		17/02/01
                        Changed the code  to    store    all    global
                        variables in an array. Changed  the  package's
                        type from extension to feature so that it  now
                        removes  itself    properly.    Changed    all
                        buttonAlert   instructions    for    PreAlpha8
                        compatibility. Changed license to BSD.


====================
More Cols Package
====================

The 'More Cols' Package (moreCols.tcl) adds a few more  capacities  to
the 'Manip Cols' Package. It allows conversion of text tables  to  and
from Html or Latex formats. When it is activated, a new submenu called
<Tables Conversion> is added at the bottom of  the  Columns  menu.  It
contains the following items :
<Columns to Html>	Converts an ordinary text table to HTML  code
                        to export to an Html document.
<Columns to Latex>	Converts an ordinary text table  to  a  LaTeX
                        'tabular' environment.
    When pressing the <option> key down, the previous items become :
<Columns to Html>
<Latex to Columns>
                        They convert an HTML table   or    a    Latex
                        'tabular' (or 'array') environment    to    a
                        simple text tabulated  with    the    current
                        'columns separator'. Nested HTML  tables  are
                        handled. 

====================
License terms
====================

This software is free software distributed under the terms of the  new  BSD
license :
Redistribution and  use  in  source  and  binary  forms,  with  or  without
modification, are permitted provided that the following conditions are met:
 Redistributions of source code must retain the  above  copyright  notice,
this list of conditions and the following disclaimer.
 Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in  the  documentation
and/or other materials provided with the distribution.
 Neither the name of Bernard Desgraupes nor the names of its  contributors
may be used to endorse or  promote  products  derived  from  this  software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED  TO,  THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR  PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT,  INCIDENTAL,  SPECIAL,  EXEMPLARY,  OR  CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS  OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)  HOWEVER
CAUSED AND  ON  ANY  THEORY  OF  LIABILITY,  WHETHER  IN  CONTRACT,  STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN  ANY  WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE. 

====================
Known problems
====================

-Troubleshooting-
If sometimes a proc does not do what you expect it to do, it is very  often
because you have changed the  columns  separator  and  still  think  it  is
another one. For instance if you change the separator from '\t' to a  blank
space ' ', any word will be considered in a different  column  whereas  two
words separated by a tab will be considered in the same  column.  And  vice
versa. 


Please e-mail any problem or bug you encounter : <berdesg@easynet.fr>

Visit my Web page for updates and other Alpha utilities :
 <http://perso.easynet.fr/~berdesg/alpha.html>
There are modes for Metafont, Metapost, Omega, MPW and the Filters Menu.

Back to top of the page
